Format Date-time

R←X(1200⌶)Y

Y is a numeric array of any shape, where every element contains a Dyalog Date Number that represents a date between 1 January 0001 and 28 February 4000 in the Proleptic Gregorian Calendar.

X is a character scalar or vector specifying a pattern with which the elements in Y should be formatted.

R is an array of the same shape as Y, whose elements are enclosed character vectors.

Formatting Pattern in X

The formatting pattern allows a time number to be converted to a highly user-configurable, plain text format. When a time number is formatted, elements in the result are copies of the format pattern with format sequences replaced by the elements they represent.

The format sequences are intended to be visually reminiscent of the generated text. They use alphabetic characters easily associated with the substitution (e.g. D, M and Y for Day, Month and Year respectively) repeated one or more times to indicate format. As noted below, some sequences allow the first character to be replaced by a _, or the casing to be altered.

Format letter	Length	Meaning	Variations	Example
Year	YY	Without century	YY	19
YYYY	With century	YYYY	2019
Month	M	1 or 2 digit numeric	M	3
MM	2 character numeric	MM _M	03 3
MMM	Abbreviated name	MMM Mmm mmm _mm^{1Natural sentence case may be specified for M (month name) and d (day name) only, and causes the text to be substituted in the case which is natural for the language; some languages (e.g. English) always capitalise the first letter of day and month names whereas others (e.g. French) do not.}	MAR Mar mar Mar
MMMM	Full name	MMMM Mmmm mmmm _mmm^{1Natural sentence case may be specified for M (month name) and d (day name) only, and causes the text to be substituted in the case which is natural for the language; some languages (e.g. English) always capitalise the first letter of day and month names whereas others (e.g. French) do not.}	MARCH March march March
Day of month	D	1 or 2 digit numeric	D	4
DD	2 character numeric	DD _D	04 4
hours	h	1 or 2 digit numeric	h	8
hh	2 character numeric	hh _h	08 8
minutes	m	1 or 2 digit numeric	m	5
mm	2 character numeric	mm _m	05 5
seconds	s	1 or 2 digit numeric	s	0
ss	2 character numeric	ss _s	00 0
fractional seconds	f	1 digit precision	f	5
ff	2 digit precision	ff	55
fff	3 digit precision	fff	555
ffff	4 digit precision	ffff	5555
fffff	5 digit precision	fffff	55555
ffffff	6 digit precision	ffffff	555555
day of week	d	Numeric (1-7)	d	1
ddd	Abbreviated name	DDD Ddd ddd _dd^{1Natural sentence case may be specified for M (month name) and d (day name) only, and causes the text to be substituted in the case which is natural for the language; some languages (e.g. English) always capitalise the first letter of day and month names whereas others (e.g. French) do not.}	MON Mon mon Mon
dddd	Full name	DDDD Dddd dddd _ddd^{1Natural sentence case may be specified for M (month name) and d (day name) only, and causes the text to be substituted in the case which is natural for the language; some languages (e.g. English) always capitalise the first letter of day and month names whereas others (e.g. French) do not.}	MONDAY Monday monday Monday
ISO week number	w	1 or 2 digit numeric	w	10
ww	2 character numeric	ww _w	10 10
year of ISO Week number^{2 Dates at the start of the year may be in the final week of the previous year, and dates at the end of the year may be in the first week of the following year.}	WW	Without century	WW	19
WWWW	With century	WWWW	2019
day of year	y	1 to 3 digit numeric	y	63
yy	3 character numeric	yy _y	063 63
Ordinal indicator^{3 An ordinal indicator is a character or group of characters following a numeral, such as (in English) the suffixes -st, -nd, -rd, -th as in 1st, 2nd, 3rd, 4th.} for day of month	O	Short	O o	T t
OO	Full	OO Oo oo	TH Th th
hours in twelve hour clock	t	1 or 2 digit numeric	t	8
tt	2 character numeric	tt _t	08
AM/PM Indicator	P	Short	P p	A a
PP	Full	PP pp	AM am

The upper and lower case letters, underscore _, dollar $ and percent % are all reserved for introducing format sequences, even though not all currently have meaning. The remaining, non-reserved, characters are copied to the result unchanged, thus the format string hh:mm represents the hour of the day and minute of the hour with a colon between (e.g. 12:00). All characters or sequences of characters may be delimited by " or ' at any point in the format string to prevent them being interpreted as a part of a format sequence, and, within these delimiters, two adjacent delimiter characters produce a single delimiter.

Note: The characters AaaaBbbb consist of two adjacent format sequences because there is a sequence of As followed by a sequence of Bs. The characters AaaaAaaa consist of one format sequence because it only contains As. It can be separated into two format sequences by insering an empty " or ' - delimited string, e.g. Aaaa""Aaaa.

Language

Unless overridden, English is used for text substitutions. Different languages may be selected using the Language variant option and/or the use of language specifiers within the format pattern. In either case, the language is specified as either a two letter ISO 639-1 language code in lower case (e.g. en) or as a five character language with an additional underscore and two character region in upper case (e.g. en_GB). Within the format pattern, __xx__ (where xx is the two or five character specifier) will switch the language of the subsequent generated text. Dictionaries for the following languages are built in:

Predefined patterns

Any pattern can contain (in part or in whole) a named predefined pattern, which allows common date and time formats to be specified in abbreviated form. Predefined patterns may be specified on a per-language basis, allowing patterns to be tailored for the selected language.

ISO 639-1	Language
da	Danish
de	German
el	Greek
en	English
es	Spanish
fi	Finnish
fr	French
it	Italian
ja	Japanese
nb	Norwegian Bokmål
nl	Dutch
nn	Norwegian Nynorsk
pl	Polish
pt	Portuguese
ru	Russian
sv	Swedish
zh	Chinese

Predefined patterns are included in a pattern using % delimiters. For example, %ISO% includes the named predefined pattern ISO.

Name	Substitutes as
ISO¹	YYYY-MM-DD"T"hh:mm:ss

Additional predefined patterns may be defined using the Dictionary variant option. Predefined patterns must not contain references to other predefined patterns.

Variant Options

The Language variant option specifies the language used for formatting datetimes and defaults to 'en' (English). The option value is a two or five character name (e.g. 'en' or 'en_GB'). The setting may be explicitly overridden in the format pattern.

The Dictionary variant option specifies a namespace which contains additional or replacement names for the months etc. and/or predefined patterns, for languages and language regions.

At the top level there may be zero or more sub-namespaces with two or five character names, according to the rules for language and language regions. Within each of these, month names etc. are defined as follows:

Named item	Description
MonthNames	A twelve-element vector of character vectors containing the full names corresponding to January to December, respectively.
ShortMonthNames	A twelve-element vector of character vectors containing the short names corresponding to Jan to Dec, respectively.
WeekdayNames	A seven-element vector of character vectors containing the full names corresponding to Monday to Sunday, respectively.
ShortWeekdayNames	A seven-element vector of character vectors containing the full names corresponding to Mon to Sun, respectively.
MorningAfternoon	A two-element vector of character vectors containing the names corresponding to AM and PM, respectively.
Ordinals	A character vector containing the one ordinal used for all numbers in the range 1 to 31, or a thirty one-element vector of character vectors containing the ordinals for 1 to 31, respectively.

Also at the top level of the dictionary namespace there may be a sub-namespace named Patterns and within this further sub-namespaces named Global and/or two or five character language names, containing definitions of predefined patterns. Predefined patterns are defined in the same way as the formatting pattern except that they may not contain references to other predefined patterns.

If the namespace contains a definition which is supplied built into the interpreter, it replaces the built-in one.

If a dictionary is incomplete (e.g. is missing one of the expected named items, or one of the named items contains too few elements) an error is signalled only if the missing content would actually be needed.

Example dictionary

The following creates a dictionary defined by the namespace dict using JSON text. See the formatting examples below for uses of this dictionary.

      dict_json
{
  "Patterns": {
    "Global": {
      "ISOweek": "YYYY-'W'ww",
      "DateCompact": "D-MMM-YYYY",
      "DateVerbose": "'the date is' DD _mm YYYY"
    },
    "fr": {
      "DateVerbose": "'la date est le' DD mmm YYYY"
    },
    "en_US": {
      "DateVerbose": "'the date is' Mmm DD, YYYY"
    }
  },
  "en_US": {
    "ShortMonthNames": [
      "Jan.", "Feb.", "Mar.", "Apr.", "May", "June",
      "July", "Aug.", "Sept.", "Oct.", "Nov.", "Dec."
    ]
  },
  "cy": {
    "MonthNames": [
      "Ionawr", "Chwefror", "Mawrth", "Ebrill", "Mai", "Mehefin",
      "Gorffennaf", "Awst", "Medi", "Hydref", "Tachwedd", "Rhagfyr"
    ],
    "ShortMonthNames": [
      "Ion", "Chw", "Maw", "Ebr", "Mai", "Meh",
      "Gor", "Awst", "Medi", "Hyd", "Tach", "Rhag"
    ],
    "WeekdayNames": [
      "Dydd Sul", "Dydd Llun", "Dydd Mawrth", "Dydd Mercher",
      "Dydd Iau", "Dydd Gwener", "Dydd Sadwrn"
    ],
    "ShortWeekdayNames": [
      "Sul", "Llun", "Maw", "Mer", "Iau", "Gwen", "Sad"
    ],
    "MorningAfternoon": [
      "yb", "yh"
    ],
    "Ordinals": [
      "af", "il", "ydd", "ydd", "ed", "ed", "fed", "fed", "fed",
      "fed", "eg", "fed", "eg", "eg", "fed", "eg", "eg", "fed",
      "eg", "fed", "ain", "ain", "ain", "ain", "ain", "ain",
      "ain", "ain", "ain", "ain", "ain"
    ]
  }
}
      dict←⎕JSON dict_json

Formatting Pattern in X

Language

Predefined patterns

Variant Options

Example dictionary

Note the following:

English

English (US)

Danish

Welsh (using the dictionary defined above)